<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<topic id="topic1">
  <title>gpperfmon_install</title>
  <body>
    <p>Installs the <codeph>gpperfmon</codeph> database and optionally enables the data collection
      agents.</p>
    <section id="section2">
      <title>Synopsis</title>
      <codeblock><b>gpperfmon_install --port <varname>gpdb_port</varname> </b>
      [<b>--enable</b> <b>--password</b> <varname>gpmon_password</varname> [<b>--pgpass</b> <varname>path_to_file</varname>]]
      [<b>--verbose</b>]

<b>gpperfmon_install</b> <b>--help</b> | <b>-h</b> | <b>-?</b></codeblock>
    </section>
    <section id="section3">
      <title>Description</title>
      <note otherprops="pivotal">Do not run the <codeph>gpperfmon_install</codeph> utility if you
        plan to use Pivotal Greenplum Command Center to manage your Greenplum Database system.
        Command Center no longer uses the history tables that <codeph>gpperfmon_install</codeph>
        creates. Enabling the gpperfmon data collection agents (<codeph>gpmmon</codeph> and
          <codeph>gpsmon</codeph>) adds unnecessary load to the system. Instead, run the Command
        Center installer. The installer creates the <codeph>gpperfmon</codeph> database with the
          <codeph>gpmetrics</codeph> schema Command Center needs and enables the Command Center
        agent (<codeph>ccagent</codeph>) to collect real-time system metrics and query information
        from the Greenplum Database metrics collector module. See the <xref
          href="https://gpcc.docs.pivotal.io/latest/welcome.html" format="html" scope="external"
          >Greenplum Command Center</xref> documentation for more information. </note>
      <p>The <codeph>gpperfmon_install</codeph> utility automates the steps required to enable the
        data collection agents. You must be the Greenplum Database system user
          (<codeph>gpadmin</codeph>) to run this utility. The <codeph>--port</codeph> option is
        required. When using the <codeph>--enable</codeph> option, the <codeph>--password</codeph>
        option is also required. Use the <codeph>--port</codeph> option to supply the port of the
        Greenplum Database master instance. If using the <codeph>--enable</codeph> option, Greenplum
        Database must be restarted after the utility completes.</p>
      <p>When run without the <codeph>--enable</codeph> option, the utility just creates the
          <codeph>gpperfmon</codeph> database (the database used to store system metrics collected
        by the data collection agents). When run with the <codeph>--enable</codeph> option, the
        utility also runs the following additional tasks necessary to enable the performance monitor
        data collection agents:</p>
      <ol>
        <li id="ou143278">Creates the <codeph>gpmon</codeph> superuser role in Greenplum Database.
          The data collection agents require this role to connect to the database and write their
          data. The <codeph>gpmon</codeph> superuser role uses MD5-encrypted password authentication
          by default. Use the <codeph>--password</codeph> option to set the <codeph>gpmon</codeph>
          superuser's password.</li>
        <li id="ou143437">Updates the <codeph>$MASTER_DATA_DIRECTORY/pg_hba.conf</codeph> file. The
          utility adds these lines to the host-based authentication file
            (<codeph>pg_hba.conf</codeph>):<codeblock>local      gpperfmon     gpmon                 md5
host       all           gpmon  127.0.0.1/28   md5
host       all           gpmon  ::1/128        md5</codeblock><p>The
            second and third lines, the <codeph>host</codeph> entries, give <codeph>gpmon</codeph>
            access to all Greenplum Database databases.</p><note>It might be necessary to edit the
            lines in the <codeph>pg_hba.conf</codeph> file after running the
              <codeph>gpperfmon_install</codeph> utility to limit the <codeph>gpmon</codeph> role's
            access to databases or to change the authentication method. After you edit the file, run
              <codeph>gpstop -u</codeph> to reload the file in Greenplum Database.<ul
              id="ul_ffm_ysw_k5">
              <li>To limit <codeph>gpmon</codeph> access to just the <codeph>gpperfmon</codeph>
                database, edit the <codeph>host</codeph> entries in the<codeph>pg_hba.conf</codeph>
                file. For the <codeph>gpmon</codeph> user change the second field from
                  <codeph>all</codeph> to
                <codeph>gpperfmon</codeph>:<codeblock>local      gpperfmon     gpmon                  md5
host       <b>gpperfmon</b>     gpmon    127.0.0.1/28  md5
host       <b>gpperfmon</b>     gpmon    ::1/128       md5</codeblock></li>
              <li>
                <p>The <codeph>gpperfmon_install</codeph> utility assumes the default MD5
                  authentication method. Greenplum Database can optionally be configured to use the
                  SHA-256 hash algorithm to compute the password hashes saved in the system catalog.
                  This is incompatible with the MD5 authentication method, which expects an MD5 hash
                  or clear text password in the system catalog. Because of this, if you have enabled
                  the SHA-256 hash algorithm in the database, you must edit the
                    <codeph>pg_hba.conf</codeph> file after running the
                    <codeph>gpperfmon_install</codeph> utility. For the <codeph>host</codeph>
                  entries, change the authentication method for the <codeph>gpmon</codeph> role from
                    <codeph>md5</codeph> to
                  <codeph>password</codeph>:<codeblock>local      gpperfmon     gpmon                 md5 
host       all           gpmon  127.0.0.1/28   <b>password</b>
host       all           gpmon  ::1/128        <b>password</b></codeblock></p>
                <p>The <codeph>password</codeph> authentication method submits the user's clear text
                  password for authentication and should not be used on an untrusted network. See
                  "Protecting Passwords in Greenplum Database" in the <i>Greenplum Database
                    Administrator Guide</i> for more information about configuring password
                  hashing.</p>
              </li>
            </ul></note></li>
        <li id="ou143384">Updates the password file (<codeph>.pgpass</codeph>). In order to allow
          the data collection agents to connect as the <codeph>gpmon</codeph> role without a
          password prompt, you must have a password file that has an entry for the
            <codeph>gpmon</codeph> user. The utility adds the following entry to your password file
          (if the file does not exist, the utility will create
          it):<codeblock>*:5432:gpperfmon:gpmon:<varname>gpmon_password</varname></codeblock> If
          your password file is not located in the default location (<codeph>~/.pgpass</codeph>),
          use the <codeph>--pgpass</codeph> option to specify the file location.</li>
        <li id="ou140687">Sets the server configuration parameters for the
            <codeph>gpperfmon</codeph> database. The following parameters must be enabled for the
          data collection agents to begin collecting data. The utility sets the following parameters
          in the Greenplum Database <codeph>postgresql.conf</codeph> configuration files:<ul
            id="ul_wrp_dtx_wr">
            <li><codeph>gp_enable_gpperfmon=on</codeph> (in all <codeph>postgresql.conf</codeph>
              files)</li>
            <li><codeph>gpperfmon_port=8888</codeph> (in all <codeph>postgresql.conf</codeph> files) </li>
            <li><codeph>gp_external_enable_exec=on</codeph> (in the master
                <codeph>postgresql.conf</codeph> file)</li>
          </ul><p>Data collection agents can be configured by setting parameters in the
              <codeph>gpperfmon.conf</codeph> configuration file. See <xref
              href="#topic1/section_p51_bxc_wz" format="dita"/> for details.</p><p
            otherprops="pivotal">For information about Greenplum Command Center, see the <xref
              href="https://gpcc.docs.pivotal.io" format="html" scope="external">Greenplum Command
              Center Documentation</xref>.</p></li>
      </ol>
    </section>
    <section id="section4">
      <title>Options</title>
      <parml>
        <plentry>
          <pt>--enable</pt>
          <pd>In addition to creating the <codeph>gpperfmon</codeph> database, performs the
            additional steps required to enable the data collection agents. When
              <codeph>--enable</codeph> is specified the utility will also create and configure the
              <codeph>gpmon</codeph> superuser account and set the gpperfmon server configuration
            parameters in the <codeph>postgresql.conf</codeph> files.</pd>
        </plentry>
        <plentry>
          <pt>--password <varname>gpmon_password</varname></pt>
          <pd>Required if <codeph>--enable</codeph> is specified. Sets the password of the
              <codeph>gpmon</codeph> superuser. Disallowed if <codeph>--enable</codeph> is not
            specified.</pd>
        </plentry>
        <plentry>
          <pt>--port <varname>gpdb_port</varname></pt>
          <pd>Required. Specifies the connection port of the Greenplum Database master.</pd>
        </plentry>
        <plentry>
          <pt>--pgpass <varname>path_to_file</varname></pt>
          <pd>Optional if <codeph>--enable</codeph> is specified. If the password file is not in the
            default location of <codeph>~/.pgpass</codeph>, specifies the location of the password
            file.</pd>
        </plentry>
        <plentry>
          <pt>--verbose</pt>
          <pd>Sets the logging level to verbose.</pd>
        </plentry>
        <plentry>
          <pt>--help | -h | -?</pt>
          <pd>Displays the online help.</pd>
        </plentry>
      </parml>
    </section>
    <section id="section_p51_bxc_wz">
      <title>Data Collection Agent Configuration</title>
      <p>The <codeph>$MASTER_DATA_DIRECTORY/gpperfmon/conf/gpperfmon.conf</codeph> file stores
        configuration parameters for the data collection agents. For configuration changes to these
        options to take effect, you must save <codeph>gpperfmon.conf</codeph> and then restart
        Greenplum Database server (<codeph>gpstop -r</codeph>).</p>
      <p>The <codeph>gpperfmon.conf</codeph> file contains the following configuration
        parameters.</p>
      <simpletable frame="all" id="simpletable_xhc_qtc_wz">
        <sthead>
          <stentry>Parameter</stentry>
          <stentry>Description</stentry>
        </sthead>
        <strow>
          <stentry>log_location</stentry>
          <stentry>Specifies a directory location for gpperfmon log files. Default is
              <codeph>$MASTER_DATA_DIRECTORY/gpperfmon/logs</codeph>.</stentry>
        </strow>
        <strow>
          <stentry>min_query_time</stentry>
          <stentry>
            <p>Specifies the minimum query run time in seconds for statistics collection. All
              queries that run longer than this value are logged in the
                <codeph>queries_history</codeph> table. For queries with shorter run times, no
              historical data is collected. Defaults to 20 seconds.</p>
            <p>If you know that you want to collect data for all queries, you can set this parameter
              to a low value. Setting the minimum query run time to zero, however, collects data for
              even trivial queries and can create a large amount of data that may not be useful.</p>
          </stentry>
        </strow>
        <strow>
          <stentry>max_log_size</stentry>
          <stentry>
            <p>This parameter is not included in <codeph>gpperfmon.conf</codeph>, but it may be
              added to this file.</p>
            <p>To prevent the log files from growing to excessive size, you can add the
                <codeph>max_log_size</codeph> parameter to <codeph>gpperfmon.conf</codeph>. The
              value of this parameter is measured in bytes. For example:</p>
            <codeblock>max_log_size = 10485760</codeblock>
            <p>With this setting, the log files will grow to 10MB before the system rolls over to a
              new log file.</p>
          </stentry>
        </strow>
        <strow>
          <stentry>partition_age</stentry>
          <stentry>The number of months that gpperfmon statistics data will be retained. The default
            value is 0, which means that partitions are never dropped automatically.</stentry>
        </strow>
        <strow>
          <stentry>quantum</stentry>
          <stentry>Specifies the time in seconds between updates from data collection agents on all
            segments. Valid values are 10, 15, 20, 30, and 60. Defaults to 15 seconds.<p>If you
              prefer a less granular view of performance, or want to collect and analyze minimal
              amounts of data for system metrics, choose a higher quantum. To collect data more
              frequently, choose a lower value.</p></stentry>
        </strow>
        <strow>
          <stentry>harvest_interval</stentry>
          <stentry>The time, in seconds, between data harvests. A data harvest moves recent data
            from the <codeph>gpperfmon</codeph> external (<codeph>_tail</codeph>) tables to their
            corresponding history files. The default is 120. The minimum value is 30. </stentry>
        </strow>
        <strow>
          <stentry>smdw_aliases</stentry>
          <stentry>This parameter allows you to specify additional host names for the standby
            master. For example, if the standby master has two NICs, you can
            enter:<codeblock>smdw_aliases=smdw-1,smdw-2</codeblock></stentry>
        </strow>
      </simpletable>
    </section>
    <section>
      <title>Notes</title>
      <p>The <codeph>gpperfmon</codeph> database requires the <codeph>gpmon</codeph> role. After the
          <codeph>gpperfmon</codeph> database and <codeph>gpmon</codeph> role have been created, you
        can change the password for the <codeph>gpmon</codeph> role: </p>
      <ol id="ol_wss_knp_wr">
        <li>Log in to Greenplum Database as a superuser and change the <codeph>gpmon</codeph>
          password with the <codeph>ALTER ROLE</codeph>
          command.<codeblock># ALTER ROLE gpmon WITH PASSWORD '<varname>new_password</varname>' ;</codeblock></li>
        <li>Update the password in the <codeph>.pgpass</codeph> file. The default file location is
          the <codeph>gpadmin</codeph> home directory (<codeph>~/.pgpass</codeph>). The
            <codeph>.pgpass</codeph> file contains a line with the <codeph>gpmon</codeph>
          password.<codeblock>*:5432:gpperfmon:gpmon:<varname>new_password</varname></codeblock></li>
      </ol>
      <p>The gpperfmon monitoring system requires some initialization after startup. Monitoring
        information appears after a few minutes have passed, and not immediately after installation
        and startup of the gpperfmon system.</p>
    </section>
    <section id="section5">
      <title>Examples</title>
      <p>Create the <codeph>gpperfmon</codeph> database only:</p>
      <codeblock>$ su - gpadmin
$ gpperfmon_install --port 5432</codeblock>
      <p>Create the <codeph>gpperfmon</codeph> database, create the <codeph>gpmon</codeph>
        superuser, and enable the data collection agents:</p>
      <codeblock>$ su - gpadmin
$ gpperfmon_install --enable --password changeme --port 5432
$ gpstop -r</codeblock>
    </section>
    <section id="section6">
      <title>See Also</title>
      <p>
        <codeph>
          <xref href="./gpstop.xml#topic1" type="topic" format="dita"/>
        </codeph>
      </p>
    </section>
  </body>
</topic>
